/**
 * TestAgent 扩展的类型定义
 * 
 * 这个文件定义了前后端通信和数据结构的所有类型
 */

// ============================================================================
// 消息相关类型
// ============================================================================

/**
 * 消息类型
 */
export type MessageType = 
    | 'user'           // 用户消息
    | 'assistant'      // AI 助手消息
    | 'system'         // 系统消息
    | 'tool-call'      // 工具调用
    | 'tool-result';   // 工具结果

/**
 * 消息状态
 */
export type MessageStatus = 
    | 'sending'    // 发送中
    | 'sent'       // 已发送
    | 'streaming'  // 流式接收中
    | 'complete'   // 完成
    | 'error';     // 错误

/**
 * 附件类型
 */
export interface Attachment {
    type: 'file';           // 附件类型（目前只支持文件）
    path: string;           // 文件绝对路径
    name: string;           // 文件名
    relativePath?: string;  // 相对于工作区的路径
    language?: string;      // 语言类型（用于代码高亮）
    size?: number;          // 文件大小（字节）
    content?: string;       // 文件内容（可选，按需加载）
}

/**
 * 工具调用状态
 */
export type ToolCallStatus = 
    | 'pending'    // 待执行
    | 'running'    // 执行中
    | 'success'    // 成功
    | 'error'      // 错误
    | 'cancelled'; // 已取消

/**
 * 工具调用信息
 */
export interface ToolCall {
    id: string;              // 工具调用唯一ID
    toolId: string;          // 工具标识符
    toolName: string;        // 工具显示名称
    args?: Record<string, any>; // 工具参数
    status: ToolCallStatus;  // 执行状态
    startTime?: number;      // 开始时间戳
    endTime?: number;        // 结束时间戳
}

/**
 * 工具执行结果
 */
export interface ToolResult {
    callId: string;          // 对应的工具调用ID
    success: boolean;        // 是否成功
    output?: string;         // 成功输出内容
    error?: string;          // 错误信息
    exitCode?: number;       // 退出码（命令执行时使用）
    duration?: number;       // 执行耗时（毫秒）
    source?: 'manual' | 'ai'; // 调用来源：手动调用或AI调用
}

/**
 * 手动工具执行记录
 * 用于持久化用户在工具面板的手动操作
 */
export interface ManualToolHistoryItem {
    id: string;             // 记录唯一ID
    toolId: string;         // 工具ID
    toolName: string;       // 工具名称 (快照)
    args: any;              // 执行参数 (快照)
    result: ToolResult;     // 执行结果
    timestamp: number;      // 执行时间
}

/**
 * 统一消息结构
 */
export interface Message {
    id: string;                     // 消息唯一标识
    type: MessageType;              // 消息类型
    status: MessageStatus;          // 消息状态
    content: string;                // 文本内容
    timestamp: number;              // 时间戳
    attachments?: Attachment[];     // 附件列表
    toolCall?: ToolCall;            // 工具调用信息（仅当 type='tool-call' 时）
    toolResult?: ToolResult;        // 工具结果（仅当 type='tool-result' 时）
    needConfirmation?: boolean;     // 是否需要用户确认
    confirmed?: boolean;            // 用户是否已确认
}

// ============================================================================
// 工具相关类型
// ============================================================================


/**
 * 工具定义
 */
export interface ToolDefinition {
    id: string;                  // 工具唯一标识
    name: string;                // 工具显示名称
    description: string;         // 工具描述
    icon: string;                // codicon 图标名（不含 'codicon-' 前缀）
    requireConfirm: boolean;     // 是否需要用户确认
    enabled: boolean;            // 是否启用
    parameters?: ToolParameter[]; // 工具参数定义
}

/**
 * 工具参数定义
 */
export interface ToolParameter {
    name: string;           // 参数名
    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'text' | 'enum';
    description: string;    // 参数描述
    required: boolean;      // 是否必需
    defaultValue?: any;     // 默认值
    options?: Array<{       // 枚举选项（当 type='enum' 时使用）
        label: string;      // 显示文本
        value: string;      // 实际值
    }>;
}

// ============================================================================
// 前后端通信消息类型
// ============================================================================

/**
 * 从 Webview 发送到扩展后端的消息类型
 */
export type WebviewToExtensionMessage = 
    | { type: 'sendMessage'; text: string; attachments?: Attachment[] }
    | { type: 'clearChat' }
    | { type: 'selectTool'; toolId: string }
    | { type: 'callTool'; toolId: string; args?: Record<string, any> }
    | { type: 'confirmAction'; messageId: string; confirmed: boolean }
    | { type: 'cancelTool'; callId: string }
    | { type: 'requestContext' }  // 请求选择文件作为上下文
    | { type: 'requestToolList' }  // 请求工具列表
    | { type: 'removeAttachment'; index: number }
    | { type: 'webviewReady' }  // 前端加载完成,请求恢复状态
    | { type: 'toolConfirmationResponse'; messageId: string; approved: boolean };  // 工具确认响应

/**
 * 从扩展后端发送到 Webview 的消息类型
 */
export type ExtensionToWebviewMessage = 
    | { type: 'response'; text: string } 
    | { type: 'error'; text: string }  
    | { type: 'clearSuccess' } 
    | { type: 'message'; message: Message }  
    | { type: 'updateMessage'; messageId: string; updates: Partial<Message> }  
    | { type: 'toolResult'; result: ToolResult }
    | { type: 'streamChunk'; messageId: string; chunk: string } 
    | { type: 'clearStreamMessage'; messageId: string } 
    | { type: 'filesSelected'; files: Attachment[] } 
    | { type: 'toolList'; tools: ToolDefinition[] }  
    | { type: 'toolConfirmation'; toolCall: { id: string; name: string; args: any }; messageId: string }
    // [新增] 历史记录恢复消息
    | { type: 'restoreHistory'; messages: Message[] } 
    | { type: 'restoreManualHistory'; history: ManualToolHistoryItem[] };
    

    

// ============================================================================
// 命令执行相关类型
// ============================================================================

/**
 * 命令执行选项
 */
export interface CommandExecutionOptions {
    command: string;        // 要执行的命令
    cwd?: string;          // 工作目录
    timeout?: number;      // 超时时间（毫秒）
    shell?: boolean;       // 是否使用 shell
}

/**
 * 命令执行结果
 */
export interface CommandExecutionResult {
    success: boolean;      // 是否成功
    stdout: string;        // 标准输出
    stderr: string;        // 错误输出
    exitCode: number;      // 退出码
    duration: number;      // 执行耗时（毫秒）
    error?: string;        // 错误信息
}


// ============================================================================
// 消息订阅者类型，接收ExtensionToWebviewMessage类型的消息并返回一个Promise<void>
// ============================================================================

// ============================================================================

export type MessageSubscriber = (message: WebviewToExtensionMessage) => Promise<void>;

// ============================================================================
// 配置类型
// ============================================================================

/**
 * SessionStore 配置
 */
export interface SessionStoreConfig {
    maxMessages?: number;           // 最大消息数,默认 100
    maxManualHistory?: number;      // 最大手动工具历史数,默认 50
    maxContextFiles?: number;       // 最大上下文文件数,默认 10
}
